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of  contract  number  F30602-76-C-0408  with  the  Rome  Air 
Development  Center.  It  is  one  of  four  companion 
volumes  * 


* JOVIAL  Structured  Design  Diagrammer  (JSDD) 

Report  Summary 

This  document  is  a summary  of  the  contents  of 
the  JSDD  Final  Report. 

* JOVIAL  Structured  Design  Diagrammer  (JSDD) 

Final  Report 

This  volume  presents  the  design  techniques 
for  implementing  the  JSDD  and  describes  the 
use  of  Structured  Design  Diagrams. 

* JOVIAL  Structured  Design  Diagrammer  (JSDD) 

Program  Description 

This  volume  presents  a detailed  description 
of  the  program  implementation  for  purposes  of 
maintaining  and/or  modifying  the  JSDD. 


* JOVIAL  Structured  Design  Diagrammer  (JSDD) 
User's  Manual 

This  volume  presents  the  user's  view  of  the 
JSDD  along  with  user  options  and  other 
Information  about  running  the  program. 
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I.  Introduction 

Thio  document  is  a user-oriented  description  of  the 
input/output  files  and  operating  procedures  necessary  to  run 
the  JOVIAL  Structured  Design  Diagrammer  (JSDD). 

The  JOVIAL  Structured  Design  Diagrammer  is  designed  to  run 
on  all  Honeywell  Information  Systems  Inc.  Series  6000 
computers  providing  for  application  program  use  at  least  one 
disk  drive,  one  line  printer,  and  96K  of  user  memory. 
Additionally,  the  computer  system  should  include  as  much 
extra  memory  and  as  many  extra  input/output  devices  as  are 
required  to  execute  the  JSDD  under  control  of  the  Honeywell 
Information  Systems  Inc.  Series  60  Level  66  and  Series  6000 
General  Comprehensive  Operating  Supervisor  (GCOS)  Version 
1/G.  The  consequences  of  running  the  JSDD  on  another 
computer  or  operating  system  have  not  been  determined.  The 
fact  that  the  JSDD  is  written  in  JOVIAL  J3  (a  JOCIT 
compiler)  raises  hopes  that  it  may  in  fact  be  portable. 


The  JSDD  produces  a graphical  representation  of  the  control 
and  processing  structure  of  programs  written  in  the  JOVIAL 
J3  programming  language,  with  or  without  structured 
extensions  (see  Final  Report,  Section  6).  It  can  be 
thought  of  as  the  first  component  of  an  integrated  software 
analysis  and  documentation  system  which  addresses  itself  to 
the  problem  of  standardizing  the  loose  collection  of 
software  design  guidelines  known  as  "structured 
programming."  This  first  component  consists  of  an 
automated  documentation  system  which  produces  two  types  of 
diagrams*  Structured  Design  Diagrams  (SDDs)  and  Invocation 
Diagrams.  SDDs  provide  a graphic  display  of  program 
control  logic.  Invocation  Diagrams  are  a display  of  a 
software  system's  functional  (calling)  structure. 

The  experienced  systems  programmer  will  find  the  SDD  and 
Invocation  Diagram  valuable  aids  in  understanding  unfamiliar 
programs.  The  SDD  makes  nested  control  logic  transparent 
and  readable,  while  the  Invocation  Diagram  provides  a 
detailed  control  map  at  a procedural  level  of  abstraction. 
Both  of  these  tasks  must  be  completed  manually  in  the 
absence  of  automated  tools. 

The  JSDD  has  additional  utility  in  system  design 
applications,  because  by  its  graphical  representation  it 
highlights  use  of  unstructured  programming  constructs  as 


well  as  poorly-considered  control  paths.  Thus,  it  can  be 
used  as  a tool  to  encourage  (and  with  incorporation  into  a 
larger  software  analysis  and  documentation  system,  enforce) 
good  programming  practices. 

The  use  of  the  JSDD  programs  requires  an  understanding  of 
the  JSDD  diagrams  produced  as  output;  thus,  the  User-'s 
Manual  is  arranged  to  reflect  this  prerequisite.  First, 
Section  2 discusses  SDDs  and  Section  3 discusses  Invocation 
Diagrams.  Section  4 then  gives  a general  overview  of  JSDD 
running  procedures.  Section  5 expands  upon  Section  4 by 
describing  the  various  options  available  to  the  JSDD  user. 
Finally,  Section  6 introduces  the  control  cards  necessary  to 
run  the  JSDD  programs  in  the  MULTICS  GCOS  Encapsulator 
environment. 
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2.  Structured  Design  Diagram  (SDD)  Description 


Structured  Design  Diagrams  (SDDs)  provide  a graphic  two 
' dimensional  display  of  the  nested  logical  sequences  that 

define  the  structure  of  a computer  program.  SDDs  for  JOVIAL 
J3  are  constructed  from  the  two  basic  structural  elements 
shown  in  figure  2-1. 


SEQUENTIAL  FLOW  DECISION  BRANCHING 


hioure  2-1.  SDD  Primitives 


The  rectangular  box  is  used  to  contain  elements  that  are 
executed  in  sequence.  Control  enters  from  the  top  or  left 
side  of  the  rectangle.  Each  element  in  a rectangle  is 
executed  in  sequence  and  control  flows  through  the  bottom  of 
the  box. 

The  pentagonal  box  is  used  to  contain  two  types  of  JOVIAL 
constructs*  module  heads  and  decision  making  elements.  A 
module  head  is  a <PROGRAM  HEAD>,  <PROC  DESCRI  PTOR>  or  <CLQSE 
HEAD>  (see  the  syntax  definition  of  JOVIAL  in  Section  5 of 
the  JSDD  Final  Report).  Control  passes  through  the  bottom  of 
a module  heady's  pentagonal  box  to  the  module's  code  body. 
Figures  2-2,  2-3  and  2-4  illustrate  SDD  representations  of 
module  heaas. 


figure  2-2.  SDD  representation  of  <PRLiURAM  l-iEAD> 
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Moure  <^-3,  SDU  represen  ca;,ion  of  <PR(jC  UESCR  IH1L)R> 


Eic^.ure  2-4.  SDD  representation  or  <CLDbb  H£AD> 


A decision  making  element  is  a JOVIAL  construct  wni ch 
directs  the  flow  of  control  to  one  of  two  paths.  Evaluation 
of  the  contents  of  the  pentagonal  box  determines  the  path  to 
which  control  is  passed.  Figures  2-bi  2-6,  2-7  and  2-b 
illustrate  the  SDD  representaions  of  JOVIAL's  decision 
making  elements.  Non-standard  decision  making  elements  have 
been  introduced  as  structured  extensions  to  JOVIAL  J3.  The 
structured  extensions  are  the  Do  While  Loop,  the  Do  Until 
Loop  and  the  Case  Statement.  Full  descriptions  of  these  new 
constructs  are  available  in  Section  6 of  the  JSDD  Final 
Report. 


Eioure  2-b.  SDD  representation  of  the  If  Statement, 
Do  Hhile  Loop  and  Do  Unrii  Loop 
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i-i^,ure  2-0.  SDD  representation  of  tne  tor  Loop 


hi(_,ure  2-7.  SDD  representation  of  the  Do  Case  Statement 


hicure  2-b.  SDD  representaion  of  the  Alternative  Statement 


Pentagonal  boxes  containing  decision  making  elements  are 
entered  from  the  top  or  from  the  left.  In  general,  they  are 
exited  by  taking  the  horizontal  path  (to  the  right)  or  by 
taking  the  vertical  path  (through  the  bottom  of  the 
pentagon).  The  horizontal  path  is  taken  if  the  decision 
element  is  evaluated  to  be  TRUE.  Otherwise,  the  vertical 
path  is  taken.  Note  that  the  SDD  representations  of  the  Do 
Case  Statement  and  Alternative  Statement  contain  ^•'DO  CASE" 
and  •'"IFEITH'^  decision  making  elements.  These  elements  are 
"always  evaluated  to  be  TRUE. 


If  a decision  making  element  is  evaluated  to  be  false  and 
its  pentagon  has  no  vertical  path,  then  the  SDD  execution 
path  must  be  retraced  until  a pentagon  is  found  which  has  an 
unexecuted  vertical  path.  If  such  a pentagon  is  found,  then 
the  vertical  path  must  be  followed.  If  no  such  pentagon  is 
found,  then  the  execution  of  the  module  has  been  completed. 

It  is  important  to  note  that  Goto  Statements  appear  in 
rectangular  boxes  and  their  effect  upon  a program's  flow  of 
control  is  not  illustrated  by  an  SDD.  Restrained  usage  of 
the  Goto  statement  will  result  in  SDDs  which  will  better 
Tllustrate  a program's  flow  of  control.  The  structured 
extensions  to  JOVIAL  J3  (see  JSDD  Final  Report,  Section  6) 
were  introduced  to  minimize  the  JOVIAL  programmer's  reliance 
upon  the  Goto  Statement. 

Occasionally,  the  level  of  nesting  (of  decision  making 
elements)  in  a program  makes  it  impossible  to  display  a code 
block  in  the  available  number  of  page  columns.  In  such 
cases,  it  is  necessary  for  the  JSDD  to  create  what  is 
referred  to  as  a stump.  A stump  is  a diagram  continuation. 
When  the  width  of  a page  Is  such  that  the  display  of  a code 
block  can  not  be  accommodated,  that  code  block's  logical 
position  in  the  SDD  is  filled  with  a stump  reference 
display.  The  stump  reference  display  consists  of  a stump 
reference  number  by  which  the  diagram  continuation  can  be 
located.  If  the  HEADING  option  is  on  (see  Section  5.2),  then 
the  stump  reference  number  is  the  number  of  the  page  on 
which  the  continuation  appears.  Otherwise,  the  stump 
reference  number  is  the  stump's  sequence  number. 


The  JSDD  recognizes  three  types  of  comments*  in-line 
comments,  type-1  (or  same  line)  comments  and  type-2  (or 
C-type)  comments.  In-line  comments  are  comments  which  are 
embedded  in  a JOVIAL  statement.  In-line  comments  are 
displayed  in  their  embedding  statements  in  SDDs.  A type-1 
comment  is  a comment  which  begins  on  the  same  line  as  a 
IQVIAL  statement  in  the  input  file.  In  SDDs,  type-1  comments 
appear  below  the  statements  to  which  they  refer.  A type-2 
comment  is  a comment  which  appears  by  itself  in  the  input 
file.  SSDs  display  type-2  comments  next  to  the  line  which 
connects  the  code  blocks  which  precede  and  succeed  the 
comment. 

r-igure  is  a sample  page  from  a desian  diagram 
by  the  JSDD  system. 
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higure  2-V.  Sample  pane  of  SDD  output 


3.  Invocation  Diagram  Description 

The  Invocation  Diagrammer  produces  two  different  outputs* 
( I ) a list  of  procedures  that  are  members  of  one  or  more 
recursive  invocation  loops,  and  (2)  the  Invocation  Diagram 
itself . 

The  first  output,  if  it  appears  on  the  diagram,  occurs 
before  the  actual  diagram  under  the  heading  "ULTIMATELY 
SELF-RECURSIVE."  Under  it  are  listed  all  procedures  that 
call  themselves,  either  directly  or  indirectly.  An  example 
of  a direct  recursive  call  is  a procedure  which  contains,  as 
part  of  its  code,  a call  to  itself.  Indirectly  recursive 
calls  are  best  illustrated,  again,  by  an  example.  Suppose 
procedure  A can  call  procedure  B which  can  call  procedure  C. 
If,  as  part  of  its  code,  procedure  C contains  a call  to 
procedure  A,  all  three  procedures  (A,  B,  and  C)  can 
theoretically  call  themselves. 

The  Invocation  Diagram  supplies  recursion  information  for 
two  reasons.  First,  the  diagrammer  has  to  detect  recursive 
procedures  because  its  algorithm  for  producing  the 
Invocation  Diagram  is  itself  recursive.  A recursive 
procedure  could  thus  cause  the  diagrammer  to  diagram 
forever.  Therefore,  recursive  procedures  are  only  expanded 
once  in  the  diagram,  and  thereafter  are  simply  printed  and 
flagged.  Since  this  affects  the  readability  of  the  diagram, 
the  recursion  information  ought  to  be  summarized  for  the 
user. 

Secondly,  it  can  be  argued  that  recursion  has  no  place  in 
JOVIAL  programs  (JOVIAL  J3  does  not  support  recursion),  and 
thus  should  be  banned.  The  recursion  information  can  be 
thought  of  as  a warning  to  the  programmer  that  illegal 
recursion  is  a possibility  in  the  submitted  program 
structure.  Note  that  the  Invocation  Diagrammer  only  reports 
the  possibi 1 Itv  of  recursion  - it  is  quite  possible  that  the 
program  in  question  avoids  actually  making  a recursive  call. 

The  second  output  is  the  Invocation  Diagram  itself.  The 
diagram  comes  in  two  parts*  a main  procedure  diagram  and 
diagrams  of  continuations  and  independent  routines.  The 
diagram  of  the  main  procedure,  if  it  occurs,  occurs  first. 
Invocation  Diagrams  are  quite  simple  to  read  - all  procedure 
names  which  are  connected  horizontally  to  a vertical  line 
are  called  by  the  procedure  whose  name  started  the  vertical 
line.  If  the  main  program  exists,  it  is  the  top  level  of 


the  diagram.  For  example! 

j 

PROCl 

^ * 

/ — PH0C2+ 

y y 

/ y — PR0C3 

y / y 

y / y_pRQC4 

y y 

' PttCIC5* 

y 

In  this  example,  PRDCl  calls  PR0C2,  PH0C3,  and  PH0C5. 
Additionally,  we  see  that  PR0C3  calls  PRQC4,  and  some 
Invisible  procedure  calls  PRDCl.  That  procedure  is  at  the 
top  level  of  this  particular  diagram,  because  PRDCl  hangs 
off  the  leftmost  vertical  line  possible.  There  is  still 
more  information  here;  we  know  PRDC2  is  an  external 
procedure  because  it  is  flagged  with  a PRDCb  is 

recursive  - it  is  flagged  with  a 

Main  diagram  continuations  (caused  by  running  off  the  right 
side  of  the  page)  and  independent  procedures  (procedures  not 
called  by  any  of  the  procedures  which  are  directly  or 
indirectly  called  by  the  main  program)  occur  at  the  end  of 
the  diagram,  under  the  heading  "CDNTI NUATIDNS  AND 
INDEPENDENT  RDUTINES."  Continuations  consist  of  “stumps" 
which  correspond  to  similar  "stumps"  in  the  main  diagram. 
If  confronted  by* 

y 

In  the  main  program,  the  user  can  find  the  continuation 
below,  which  starts  with* 

3 

y 

y 

etc. 


Stump  continuations  occur  in  numerical  order,  after 
Independent  procedure  diagrams. 


regardless  of  whether  they  are  called  (directly  or 
indirectly)  by  the  main  program.  However,  the  fact  that  a 
procedure  is  not  called  directly  or  indirectly  by  the  main 
program  is  not  a guarantee  that  it  will  appear  as  an 
"independent"  procedure.  It  is  quite  possible  that  a second 
"independent"  procedure  whose  diagram  is  output  before  that 
of  the  first  procedure  may  call  the  first.  In  that  case, 
the  first  procedure's  "independent"  diagram  is  suppressed. 
Nevertheless,  the  first  procedure's  diagram  will  have  been 
generated  as  part  of  the  second  procedure's  diagram.  No 
procedure  will  ever  remain  both  uncalled  and  undiagrammed. 


Tw  ^ ■ — — — - 


4.  Running  the  JSDD  System 

The  JSDD  system  consists  of  three  programs*  the  Design 
^ Diagram  Data  Base  Generator  (DDDG)»  the  Design  Diagram 

Generator  (DDG)  and  the  Invocation  Diagrammer. 

The  DDDG  performs  a syntactic  analysis  of  the  input  JOVIAL 
program  and  outputs  a three  file  data  base  (for  use  by  the 
DDG  and  the  Invocation  Diagrammer).  The  DDDG  is  designed  to 
analyze  any  program  that  has  been  compiled  by  JOVIAL  J3  with 
1 no  error  or  warning  messages.  Only  one  JOVIAL  J3  constraint 

has  been  altered  - the  largest  DEFINE  directive  that  may 
occur  is  one  containing  132  characters  (instead  of  300), 
However,  neither  of  these  limits  is  a real  constraint  on 
DEFINE  directive  size,  since  DEFINES  can  be  nested  to  any 
‘ depth. 

The  DDG  outputs  a Structured  Design  Diagram  (SDD)  of  the 

input  program  in  the  format  specified  by  the  preset 
variables  in  the  compool  OPT  (see  Section  5,2). 

The  Invocation  Diagrammer  outputs  an  invocation  diagram  of 
the  input  program  in  the  format  specified  by  the  preset 
variables  in  the  compool  OPT. 

Since  all  diagram  formatting  is  performed  by  the  DDG  and 
Invocation  Diagrammer,  one  execution  of  the  DDDG  on  an  input 
program  is  sufficient  to  produce  diagrams  having  a wide 
variety  of  formats. 

The  DDDG  (DDDG. OBJ)  must  be  loaded  with  the  object  segments 
SYNTH. OBJ,  NTABLES.OBJ,  DATA. OBJ  and  SPOOL. OBJ.  The  DDDG 
requires  five  files* 

(logical  unit  number) 

1 1 

The  JOVIAL  program  to  be  diagrammed. 

12 

The  DDDG  message  file.  This  file  will  contain  any 
error  messages  generated  by  the  DDDG  execution. 

13 

FILE  I (see  the  JSDD  Program  Description  Section 

4.4) ,  This  file  is  part  of  the  DDG  data  base. 

14 

FILE  2 (see  the  JSDD  Program  Description,  Section 

4.4) .  This  file  is  part  of  the  DDG  data  base. 

15 


16 


FILE  0 (see  the  JSDD  Program  Description,  Section 
4.4).  This  file  is  the  data  base  used  by  the 
Invocation  Diagrammer. 


The  DDG  (DDG.OBJ)  must  be  loaded  with  the  object  segments 
DPT. OBJ,  DEBUG. OBJ  and  SPOOL. OBJ.  The  DDG  operates  on  ten 
files « 


(logical 
1 1 

12 

13 

14 

15 

16 

17 

IB 

19 

20 


unit  number) 

FILE  I (from  the  DDDG). 

The  DDG  message  file.  This  file  contains  error 
messages  and  debugging  messages  generated  by  a DDG 
execution. 

FILE  2 (from  the  DDDG). 

FILE  3' \ (FILE  3 version  I - see  the  JSDD  Program 
Description,  Section  4.5.1  and  Appendix  C).  This 
file  is  part  of  the  DDG  intermediate  data  base  and 
can  be  destroyed  after  DDG  execution. 

FILE  4'' I (FILE  4 version  1 - see  JSDD  Program 

Description  Section  4.5.1  and  Appendix  C).  This 
file  is  part  of  the  DDG  intermediate  data  base  and 
can  be  destroyed  after  DDG  execution. 

PUTOUT' I (temporary  diagram  version  I).  This  file 
can  be  destroyed  after  DDG  execution. 

FINAL'OUT.  This  file  contains  the  SDD  produced  by 
the  DDG. 

FILE  3'2  (FILE  3 version  2).  This  file  is  part  of 
the  DDG  intermediate  data  base  and  can  be 
destroyed  after  DDG  execution. 

FILE  4-'2  (FILE  4 version  2).  This  file  is  part  of 
the  DDG  intermediate  data  base  and  can  be 
destroyed  after  DDG  execution. 

PUTDUT'2  (temporary  diagram  version  2).  This  file 
can  be  destroyed  after  DDG  execution. 
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The  Invocation  Diagrammer  (INVOC.OBJ)  must  be  loaded  with 
the  object  segments  GPT.OBJ  and  SPOOL. OBJ.  The  Invocation 
Diagrammer  operates  on  three  filest 

(logical  unit  number) 

1 1 

FILE  0 (from  the  DDDG). 

12 

The  Invocation  Diagrammer  message  file.  This  file 
will  contain  any  error  messages  generated  by  the 
Invocation  Diagrammer. 

13 

The  invocation  diagram. 


Section  6 contains  the  control  cards  necessary  to  run  the 
JSDD  components  on  the  MULTICS  GCOS  simulator. 
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5.  Detailed  Options 

This  section  lists  and  describes  detailed  options  for 
running  each  of  the  JSOD  programs.  Sections  5.1,  5.2,  and 
5.3  discuss  options  for  the  Design  Diagram  Database 
Generator,  the  Design  Diagram  Generator,  and  the  Invocation 
Dlagrammer,  respectively. 


5.1  DDDG  Options 

Although  most  formatting  of  the  design  diagrams  should  be 
done  with  the  DDG  options,  there  are  two  options  available 
with  the  DDDG  which  directly  Impact  the  content  and 
apoearance  of  the  final  SDDs. 

These  options  are  set  by  means  of  comment  “toggles",  which 
are  inserted  into  the  source  Input  file  by  the  user  either 
as  extra  comments  or  as  additional  text  in  existing 
comments.  The  special  form  of  the  toggle  allows  It  to  be 
distinguished  from  ordinary  comment  text.  Toggle  syntax  Is 
as  follows* 

Cl)  -'■'<any  text>  [<toggle  name>J  <any  text>-'-' 
or* 

(2)  '•'<any  text>  [•'<toggle  name>  I <any  text^'-' 

Only  the  first  toggle  in  a comment  is  processed!  all  others 
are  ignored. 

The  syn-tax  in  case  (1)  above  means  that  the  toggle  Is  to  be 
turned  ani  case  (2)  means  that  it  Is  to  be  turned  o-ff . 
These  actions  are  forced  regardless  of  the  toggle's  current 
state. 

For  example, 

"(XIMMENT  TEXT  COMMENT  TEXT! EXPAND JCOMMENT  TEXT-" 
would  turn  on  the  EXPAND  toggle,  while 
"COMMENT  TEXT  COMMENT  TEXTI'EXPANDl  COMMENT  TEXT" 
would  turn  it  off. 
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The  two  toggles  currently  available  are  EXPAND  and  ASIS. 
When  EXPAND  is  on,  the  expanded  text  of  each  DEFINE 
directive  (macro)  name  is  substituted  for  the  name.  EXPAND 
toggles  can  appear  anywhere  in  the  source  input. 

The  ASIS  toggle  is  more  complex,  but  its  use  can  lead  to 
much  improved  SDDs.  When  ASIS  is  on,  each  complete  source 
input  text  line  becomes  one  line  in  the  output  SDD.  The 
utility  of  this  can  easily  be  seeni  suppose  that  a user  had 
set  up  a portion  of  a program  (say,  data  declarations)  in  a 
special  manner,  so  that  certain  items  appeared  under  certain 
columns.  He/she  would  not  want  the  Design  Diagrammer  to 
chop  up  this  carefully  constructed  pattern,  as  it  almost 
certainly  would.  The  solution  is  to  insert  ASIS  ^'brackets* 
around  the  code  in  question.  The  Design  Diagrammer  will 
then  preserve  this  special  code  ••as-is”. 

The  only  rules  governing  placement  of  ASIS  toggles  are* 

1)  ASIS  toggles  must  come  in  pairs,  or  "brackets”!  for 
•very  Instance  of  an  ASIS  activation,  there  must  be  a 
de-activation. 

2)  ASIS  brackets  can  only  occur  where  it  would  be 
semantically  and  syntactically  legal  to  place  JOVIAL 
BEGIN-END  brackets  (this  does  not  include  use  of  BEGIN  and 
END  in  array  or  table  declarations). 

Failure  to  follow  these  rules  will  invariably  result  in 
serious  DDDG  errors  and  fatal  DDG  errors. 

There  is  another  toggle  implemented,  called  DEBUG.  This 
causes  a history  of  the  DDDG  parse  to  be  written  to  the 
error  file.  Although  useful  for  debugging,  and  for  those 
interested  in  the  mechanics  of  an  LALR(k)  parse,  DEBUG  is  of 
no  value  to  the  ordinary  user. 


5,2  DDG  Options 

The  DDG  accepts  options  which  permit  the  user  to  specify  a 
wide  variety  of  JOVIAL  Structured  Design  Diagram  formats. 

The  options  are  defined  in  a common  block  in  the  OPT  compooi 
(see  Appendix  A ). 

There  is  no  facility  currently  available  for  setting  the  DDG 
options.  Alteration  of  options  involves  editing  the  options 
compooi  and  recompiling  it. 
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The  following  is  a list  of  option  declarations 
descriptions  of  their  meanings  and  uses. 


and 


ITEM  DISPLAY'DELIM  B P 0 $ 

If  DISPLAY-'DELIM  is  on  (i.e.  preset  to  1),  BLOCK 
DELIMITERS  are  displayed  on  the  design  diagram, 
□terhwise,  they  are  not. 

BLOCK  DELIMITERS  are* 

1)  BEGINS  which  start  COMPOUND  STATEMENTS 

2)  ENDS  which  terminate  COMPOUND  STATEMENTS  and 
ALTERNATIVE  STATEMENTS 

3)  [END  DO] 

4)  [END  CASE] 

DISPLAY'^DELIM  also  controls  the  printing  of  COMMENTS 
and  LABELS  associated  with  the  BLOCK  DELIMITERS. 


It  is  recommended  that  DISPLAY'DELI M be  turned  off 
unless  the  input  program  has  important  COMMENTS  or 
LABELS  associated  with  BLOCK  DELIMITERS. 

ITEM  DOUBLE'SPACE  B P 0 $ 

If  DOUBLE''SPACE  is  on,  program  text  within  the  diagram 
is  double  spaced,  otherwise,  text  is  single  spaced. 

Double  spacing  can  increase  the  execution  time  of  the 
DDG  significantly  if  the  input  program  is  large 
(because  of  the  double  buffering  system — see  Section 
4.b.3  of  the  JSDD  Program  Description). 

It  is  recommended  that  diagrams  of  large  programs  be 
single  spaced. 

ITEM  MARGIN  I 36  S P 5 $ 

MARGIN  sets  the  left  margin  of  the  diagram.  The  above 
declaration  will  cause  five  blank  columns  to  begin  each 
line  of  the  diagram. 

ITEM  MESS'SW  I 36  S P 0 $ 

MESS'SW  directs  error  and  debug  messages  (see  JSDD 
Program  Strucure  Section  7.2)  to  either  a terminal  or 
to  an  output  file.  If  the  value  of  MESS-'SW  is  preset  to 
0,  then  output  is  directed  to  the  file  whose  device 
number  is  12.  Otherwise,  output  is  directed  to  the  user 
terminal . 


ITEM  PAGE'LNGTH  I 36  S P 60  S 

PAGE^LNGTH  should  be  set  to  the  number  of  print  lines 
on  the  paper  on  which  the  diagram  is  to  be  printed. 
PAGE'LNGTH  cannot  be  used  to  reserve  space  at  the 
bottom  of  pages  for  page  footers.  A footer  feature  is 
not  available  on  this  version  of  the  JSDD. 

ITEM  PAGE'WIDTH  I 36  S P 132  $ 

PAGE-'WIDTH  is  the  number  of  the  rightmost  column  which 
is  to  be  used  for  printing.  The  readability  of  diagrams 
is  improved  as  the  difference  of  PAGE-'WIDTH  and  MARGIN 
increases  (the  number  of  stumps  decreases).  Execution 
time  can  be  improved  by  setting  PAGE'WIDTH  to  a high 
value  and  MARGIN  to  a low  one  because  fewer  output 
lines  are  required. 

ITEM  ST'MAX  S P 35  $ 

ST'MAX  is  the  maximum  number  of  columns  which  may  be 
spanned  by  the  text  of  a statement  unit  before 
wraparound  occurs. 

In  general,  a low  valued  ST-'MAX  will  produce  a diagram 
having  fewer  stumps  than  a high  valued  ST^MAX.  However, 
a diagram  produced  with  a low  valued  ST'MAX  may  be 
difficult  to  read. 

The  value  of  PAGE-'WIDTH  should  be  considered  when 
assigning  a value  to  ST'MAX. 

ITEM  HEADING  B P I $ 

If  HEADING  is  on  page  headings  are  displayed  at  the  top 
of  each  diagram  page.  Also,  pages  are  numbered,  stumps 
are  referenced  by  page  numbers  and  a table  of  contents 
is  available. 

If  HEADING  is  off,  no  page  headings  are  displayed, 
pages  are  not  numbered,  stumps  are  referenced  by 
sequence  number  and  no  table  of  contents  is  available. 

The  HEADER,  PGM^NAME,  NAME' INDEX  and  HEAD' NO  options 
described  below  relate  to  the  HEADING  option. 

ARRAY  HEADER  10  h 150  $ 

The  HEADER  array  contains  the  text  to  be  displayed  as 
page  headings  (if  HEADING  is  on).  Elements  of  HEADER 
must  be  preset.  For  example! 

BEGIN 

21H(DRAPER  LAB  DIAGRAMMER) 

IIH(DIAGRAM  OF  ) 

END 


In  this  case,  page  three^'s  heading  might  appear* 

DRAPEH  LAB  DIAGHAMMER  PAGE  3 
DIAGRAM  OF  PROGRAM'NAME 

HEADER  ($0$)  will  always  be  followed  by  the  page  number 
which  will  start  in  column  PAGE'WIDTH-IO.  Care  should 
be  taken  to  avoid  overwriting  the  last  ten  columns. 


ITEM  PGM^NAME  h 150  $ 

PGM^'NAME  contains  the  name  of  the  program  being 
diagrammed.  The  contents  of  PGM-'NAME  wi  11  appear  in  the 
page  headings  of  pages  displaying  the  diagram  of  the 
main  program. 


ITEM  NAME' INDEX  I 36  S P I $ 

NAME'INDEX  is  the  index  into  HEADER  of  the  text  line  in 
which  the  name  of  the  program,  procedure  or  close  being 
diagrammed  will  appear.  In  the  above  example, 
NAME' INDEX  was  set  to  one.  NAME'INDEX  may  be  set  to  a 
negative  number  if  display  of  the  module  name  is  not 
desired. 


ITEM  HEAD'NO  I 36  S P 1 $ 

HEAD'NO  is  the  index  of  the  last  element  of  HEADER 
which  was  preset.  In  the  above  example,  HEAD'NO  would 
have  been  set  to  one. 

Normally  the  JSDD  leaves  one  blank  line  between  the 
page  heading  and  the  diagram  text.  The  number  of 
intervening  blank  lines  can  be  increased  by  presetting 
additional  HEADER  elements  to  IH(  ) and  incrementing 
HEAD'NO  accordingly. 

ITEM  TABLE 'OF' CONTENTS  B P 1 $ 

If  TABLE'OF'CONTENTS  and  HEADING  are  both  on,  then  a 
table  of  contents  is  generated  for  the  diagram.  The 
table  lists  the  modules  displayed  in  the  diagram  and 
the  pages  on  which  the  displays  begin. 

The  table  of  contents  appears  after  the  title  page  (if 
there  is  a title  page). 

ITEM  TITLE'SW  B P I $ 

TITLE'SW  controls  the  printing  of  the  title  page.  If  it 
is  on,  the  title  page  appears  on  page  one  (and 
subsequent  pages,  if  more  are  necessary).  The  array 
TITLE  and  TITLE'NO  also  relate  to  the  TITLE'SW  flag. 
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ARRAY  TITLE  70  H 150  $ 

The  TITLE  array  contains  the  text  to  be  displayed  on 
the  title  page.  Its  elements  are  preset  the  same  way 
that  HEADER'S  elements  are  preset.  ■* 

ITEM  TITLE'ND  I 36  S P I $ 

TITLE'NO  is  the  index  into  TITLE  of  the  last  preset 
element. 


6.3  Invocation  Dlagrammer  Options  ^ 

The  Invocation  Dlagrammer  has  only  three  user  options, 
PAGE'WIDTH,  PAGE'LNGTH,  and  PGM'NAME.  ^ All  of  these  options 
are  set  exactly  the  same  way  as  they  are  for  the  DDG.  In 
fact,  the  Invocation  Dlagrammer  uses  an  exact  copy  of  the 
DOG  options  compool  for  its  own  options.  This  being  the 
case,  the  same  compool  object  segment  .can  be  loaded  for  the 
Invocation  Dlagrammer  that  is  loaded  for  the  DDG. 

Thus,  in  most  cases  it  will  not  be  necessary  to  set 
Invocation  Dlagrammer  options  - simply  load  the  options 
compool  object  segment  used  to  run  the  DDG.  However,  if  the 
DDG  was  not  run,  or  a PAGE'WIDTH,  PAGE'LNGTH,  or  PGM'NAME 
(title  name)  change  needs  to  b’e  made,  refer  to  Section  5.2 
for  detailed  instructions  anb  default  attributes. 


6.  Control  Cards  For  Running  the  JSDD 


The  following  sections  give  detailed  GCOS  Encapsulator 
control  cards  for  running  the  various  programs  which  make  up 
the  JOVIAL  Structured  Design  Diagrammer  (JSDD).  These 
control  cards  are  applicable  to  the  GCOS  Encapsulator  system 
available  under  the  MULTICS  operating  system.  A mapping 
from  these  control  cards  to  actual  GCOS  control  cards  is 
straightforward,  made  necessary  only  by  the  differences 
between  MULTICS  and  GCOS  file  system  structure. 

Cards  common  to  all  decks  are  SNUMB,  IDENT,  LOWLOAD,  OPTION, 
LIMITS,  and  ENDJOB.  All  these  are  standard,  except  for 
LOWLOAD  and  LIMITS.  LOWLOAD  is  present  because  of  bugs  in 
both  JOVIAL  and  the  GCOS  Encapsulator  loader.  The  JOVIAL  J3 
compiler  supplied  for  this  contract  generates  incorrect 
function  linkages  which  overwrite  areas  of  low  core  at 
execution  time.  The  LOrtLOAD  card  ($  LOWLOAD  lOOCX))  causes 
a blank  area  of  10000  words  to  precede  all  programs.  This 
ensures  that  nothing  is  loaded  into  the  region  that  JOVIAL 
may  overwrite.  As  for  the  GCOS  Encapsulator  loader,  it 
simply  does  not  function  properly  without  the  LOWLOAD  card. 

The  LIMITS  card  is  included  in  all  control  card  decks.  84k 
is  the  minimum  core  region  that  should  be  specified  (92K  for 
the  DDG)  - the  time  limit  field  should  vary  with  the  size  of 
the  program  to  be  diagrammed.  Time  limits  in  the  sample 
control  cards  are  extremely  highf  the  built-in  JOVIAL 
default  should  be  adequate  in  most  cases. 

There  is  no  execute  card  in  any  of  the  sample  control  card 
decks  - this  is  because  that  card  is  included  in  the 
'•canned"  deck  which  is  inserted  at  run  time  in  place  of« 

$ select  >mlsc_llbraries> jocit>execute 

This  "canned"  deck  consists  of  the  following  cards* 

S library  z*,*z 
$ execute  dump 

$ prmfl  z*,r,r,>ml> jocit>jovlib. 020377 
$ prmfl  *z , r, s ,>ml> jocit>oldl ib. 020377 

The  dump  option  can  be  deleted  at  the  user-'s  discretion. 

Sections  6.1,  6.2,  and  6.3  contain  and  describe  the  control 
cards  used  to  execute  the  DDDG,  the  DDG,  and  the  Invocation 
Diagrammer,  respectively. 
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6.1  DDDG  Control  Cards 

The  control  cards  needed  to  execute  the  DDDG  are* 


$ 

snumb 

efs 

$ 

ident 

Strovink.558lcl4l2 

$ 

lowload 

10000 

$ 

option 

Jovial 

$ 

select 

phlS.obj 

$ 

select 

ntables.obj 

$ 

select 

data.obj 

$ 

select 

synth.obj 

$ 

select 

spool .Ob j 

$ 

select 

>mlsc_librarles>  Joclt>execute 

$ 

limits 

90,84k 

$ 

prmf  1 

I0,w,s, Jovwrk>ph IS.mon.l 1st 

$ 

prmf  1 

1 1 , w, s, ph24.gcos 

$ 

prmf  1 

l2,w,s,error24 

$ 

prmf  1 

I3,w,s,ph24f 1 

$ 

prmf  1 

I4,w,s,ph24f2 

$ 

prmf  1 

I5,w,s,ph24f0 

$ 

endjob 

Object  files  loaded  by  this  deck  are*  phlS.obj  (DDDG), 
ntables.obj  (parsing  tables),  data.obj  (global  variable 
declarations),  synth.obj  (external  SYNTH  procedure),  and 
spool. obj  (compool  object  file  for  string  package). 

Files  used  by  DDDG  are*  10  (not  currently  used),  II  (source 
input  to  DDDG),  12  (error  file),  13  (DDDG  output  file  I 
("FILE  1")),  14  (DDDG  output  file  2 ("FILE  2“)),  and  15 
(DDDG  output  file  0 ("FILE  0")). 


6.2  DDG  Control  Cards 

The  control  cards  needed  to  execute  the  DDG  are* 


$ 

snumb 

mhw 

$ 

ident 

Whitworth. 5581c 14 12 

$ 

lowload 

10000 

$ 

option 

jovial 

$ 

select 

ph24.cLj 

$ 

select 

spool .obj 

$ 

select 

opt. obj 

$ 

select 

debug. obJ 

$ 

select 

>misc_libraries> )ocit>execute 

$ 

limits 

999, 128k 

$ 

prmf  1 

10, w ,s , jovwrk>ph24.mon. list 

$ 

prmf  1 

1 1 ,w,s,ph24f  1 

$ 

prmf  1 

I2,w,s,blah 

$ 

prmf  1 

13,w,s,ph24f2 

s 

prmf  1 

14,w,s,ph24f3l 

$ 

prmf  1 

I5,w,s,ph24f4 1 

$ 

prmf  1 

I6,w,s,tmpl 

$ 

prmf  1 

l7,w,s,out''ph24f 

$ 

prmf  1 

1 8, w , s , ph24f 32 

$ 

prmf  1 

I9,w,s,ph24f42 

$ 

prmf  1 

20,w,s,tmp2 

$ 

endjob 

Object  files  loaded  by  this  deck  are*  ph24,obj  (DDG), 
spool. obj  (compool  object  file  for  string  package),  opt.obj 
(option  compool  object  file),  and  debug, obj  (debug  toggle 
compool  object  file). 

Files  used  by  the  DDG  are*  10  (not  currently  used),  II 
(“FILE  I"  from  DDDG),  12  (error  file),  13  (“FILE  2"  from 
DDDG),  14  (first  of  double-buffered  pair  of  temporary  files 
referred  to  as  “FILE  3"),  15  (first  of  double-buffered  pair 
of  temporary  files  referred  to  as  “FILE  4"),  16  (first  of 
double-buffered  pair  of  temporary  output  files),  17 
(permanent  output  file),  18  (second  of  double-buffered  pair 
of  temporary  files  referred  to  as  “FILE  3"),  19  (second  of 
double-buffered  pair  of  temporary  files  referred  to  as  “FILE 
4“),  20  (second  of  double-buffered  pair  of  temporary  output 
files ) . 

Files  14,15,16,18,19,  and  20  can  and  should  be  deleted 
following  execution  of  the  DDG.  This  can  be  accomplished  in 
the  control  card  deck  by  appropriate  changes  in  the  file 
cards.  Files  II,  12,  and  13  should  be  deleted  with 
discretion,  since  another  Design  Diagram  with  different 
format  specifications  may  be  desired. 


6.3  Invocation  Diagrammer  Control  Cards 

The  control  cards  needed  to  execute  the  Invocation 
Diagrammer  are* 

$ snumb 

$ ident 

$ lowload 

S option 

$ select 

$ select 

$ select 

$ select 

$ limits 


ef  s 

Strovink. 5581c 14  12 
10000 
jovial 
invoc.obj 
spool .Ob j 
opt.obj 

>mlsc_libraries> joci t>execute 
25,84k 
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$ 

$ 

$ 

$ 


prmf  1 10, w,s,  jovwrlc>lnvoc.mon. list 

prmf 1 1 1 ,w,s,tstf0 

prtnfl  1 2,  w,s,  errors 

prmfl  13,w,s,ph24 

endjob 


Object  files  loaded  by  this  deck  are*  invoc.obj  (Invocation 
Diagranuner ) , spool. obj  (compool  object  file  for  string 
package),  and  opt.obj  (option  compool  object  file). 


Files  used  by  the  Invocation  Diagrammer  are*  10  (not 
currently  used),  II  ("FILE  0"  from  DDDG),  12  (error  file), 
13  (Invocation  Diagrammer  output). 
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Appendix  A,  The  DDG  and  Invocation  Dlagrammer  Options 
Coinpool 

All  DDG  user  options  are  contained  In  the  compool  OPT  which 
Is  shown  below.  Setting  options  Involves  changing  the  preset 
values  In  OPT  and  recompiling  the  result. 

start  $ 

**  This  Is  the  options  compool  for  Instructions  ** 

**  in  setting  options  , see  JSDD  User's  Manual.  " 
common  options  $ 
begin 

item  display'delim  b p 0 $ 
item  double'space  b p 0 $ 
item  margin  1 36  s p 5 $ 
item  mess'sw  1 36  s p I $ 

Item  page'lngth  1 36  s p 60  $ 
item  page'width  1 36  s p 132  $ 

Item  st'max  1 36  s p 30  $ 
item  heading  b p 1 $ 
array  header  10  h 150  $ 
begin 

57h(c  s draper  laboratory  jovial  structured  design  dlagrammer) 

18h (DESIGN  DIAGRAM  OF  ) 

end 

item  pgm'name  h 160  p 21h(the  design  dlagrammer)  $ 
item  low'lim  i 36  s p 20  $ 
item  max'wldth  i 36  s p 40  $ 
item  name'lndex  i 36  s p I $ 
item  head'no  i 36  s p 1 $ 
item  table'of 'contents  b p I $ 
item  title'sw  b p I $ 
array  title  70  h 150  $ 
begin 
lh(  ) 
lh(  ) 
lh(  ) 

41h(  this  listing  consists  of  output  from) 

52h(  the  Charles  stark  draper  laboratory's  jovial  j3) 

34h(  structured  design  dlagrammer.) 

lh(  ) 

lh(  ) 

lh(  ) 

lh(  ) 

42h(  principal  designers  and  implementors  ) 

lh{  ) 

37h(  gary  w.  goddard,  csdl  staff) 
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39h(  mark  h.  whitworth,  csdl  staff) 

52h(  eric  f.  strovink,  graduate  student*  m.i.t.) 

25h(computer  science  division) 

57h(the  Charles  stark  draper  laboratory,  inc.,  Cambridge, 

lh(  ) 

end 

item  title^'no  i 36  s p 17  $ 
end 
term  $ 


ma. ) 


